Manager: Carbon Printing Manager


Carbon introduces a new printing model that allows applications to print on Mac OS 8 with existing printer drivers and on Mac OS X with new printer drivers.

On Mac OS 8, the Carbon Printing Manager calls through to the original Printing Manager functions. But on Mac OS X, Carbon applications will automatically use a new printing architecture and print through different drivers.

The following is a summary of the major changes you need to be aware of. More information is available on the Carbon website:

• The Print Record (TPrint) is no longer directly accessible by applications, and has been split into two separate opaque objects: a PrintSettings object and a PageFormat object. Applications will be given references to these two privately-defined data structures. These references are then used to query the Printing Manager for information contained within the objects.

• A consequence of splitting the Print Record and making it private is there are no fixed sizes. Applications will be able to "extend" both the PrintSettings and PageFormat objects, but applications must not assume a specific size when storing and retrieving PageFormat objects with documents.

• The Carbon Printing Manager will supply functions for flattening and restoring both the PrintSettings and PageFormat objects. When storing printing information with documents, it will suffice to store just the PageFormat object. If older versions of your application store a print record with a saved document, you may continue to do so to provide backward compatibility.

• Application developers should reduce the use of calls that append items to print dialog boxes. We expect to provide a new panel-based interface in the near future.

• There are many improvements to the QuickDraw interfaces for Carbon, including new accessor functions and data structures that should be used.

• All print records use the "draft" style, not the "deferred" style, which implies that a print driver must handle the spooling if it wants to provide spooling for the user. Many, if not all, print drivers perform their own spooling and don't require applications to call PrPicFile to implement spooling. Because it is rarely used, we are eliminating system level spooling code from the Carbon Printing Manager.

• The Carbon Printing Manager now enforces an order in which some routines are called. Any routine used out of scope will return an error.

• All Carbon Printing Manager routines are only valid within a PMBegin/PMEnd block.

• PrintSettings and PageFormats objects are automatically disposed of during a PMEnd call.

PMBegin
[ Detail ]
Prepares the Carbon Printing Manager for use.
OSStatus PMBegin()

PMBeginDocument
[ Detail ]
Initializes an imaging environment for printing a document.
OSStatus PMBeginDocument(PMPrintSettings printSettings, PMPageFormat pageFormat, PMPrintContext *printContext)

PMBeginPage
[ Detail ]
Sets up a scaling rectangle for printing a page.
OSStatus PMBeginPage(PMPrintContext printContext, const PMRect pageFrame)

PMConvertOldPrintRecord
[ Detail ]
Creates a new PMPrintSettings object and a new PMPageFormat object from an existing Printing Manager print record.
OSStatus PMConvertOldPrintRecord(Handle prRecHdl, PMPrintSettings *printSettings, PMPageFormat *pageFormat)

PMCopyPageFormat
[ Detail ]
Copies the settings from one PMPageFormat object to another.
OSStatus PMCopyPageFormat(PMPageFormat formatSrc, PMPageFormat formatDest)

PMCopyPrintSettings
[ Detail ]
Copies printing settings from one PMPrintSettings object to another.
OSStatus PMCopyPrintSettings(PMPrintSettings settingSrc, PMPrintSettings settingDest)

PMDefaultPageFormat
[ Detail ]
Initializes a PMPageFormat object to contain default page setup values for the current printer.
OSStatus PMDefaultPageFormat(PMPageFormat pageFormat)

PMDefaultPrintSettings
[ Detail ]
Initializes a PMPrintSettings object to contain the default values for the resolution, number of copies, and so on, for the current printer.
OSStatus PMDefaultPrintSettings(PMPrintSettings printSettings)

PMDisableColorSync
[ Detail ]
Disables ColorSync color matching for the current page.
OSStatus PMDisableColorSync()

PMDisposePageFormat
[ Detail ]
Releases memory previously allocated for a PMPageFormat object.
OSStatus PMDisposePageFormat(PMPageFormat pageFormat)

PMDisposePrintSettings
[ Detail ]
Releases the memory previously allocated for a PMPrintSettings object.
OSStatus PMDisposePrintSettings(PMPrintSettings printSettings)

PMEnableColorSync
[ Detail ]
Enables ColorSync color matching for the current page.
OSStatus PMEnableColorSync()

PMEnd
[ Detail ]
Closes the Printing Manager and releases its allocated memory.
OSStatus PMEnd()

PMEndDocument
[ Detail ]
Closes the open printing port.
OSStatus PMEndDocument(PMPrintContext printContext)

PMEndPage
[ Detail ]
Finishes printing the current page.
OSStatus PMEndPage(PMPrintContext printContext)

PMError
[ Detail ]
Returns the result code returned by the last Carbon Printing Manager function.
OSStatus PMError()

PMFlattenPageFormat
[ Detail ]
Flattens a PMPageFormat object for storage in a user document.
OSStatus PMFlattenPageFormat(PMPageFormat pageFormat, Handle *flatFormat)

PMFlattenPrintSettings
[ Detail ]
Flattens print settings for storage in a user document.
OSStatus PMFlattenPrintSettings(PMPrintSettings printSettings, Handle *flatSetting)

PMGeneral
[ Detail ]
Maintains compatibility with the Printing Manager function PrGeneral.
OSStatus PMGeneral(Ptr pData)

PMGetAdjustedPageRect
[ Detail ]
Reports the page size, taking into account orientation, application drawing resolution, and scale settings.
OSStatus PMGetAdjustedPageRect(PMPageFormat pageFormat, PMRect *pageRect)

PMGetAdjustedPaperRect
[ Detail ]
Reports the paper size, taking into account orientation, application drawing resolution, and scale settings.
OSStatus PMGetAdjustedPaperRect(PMPageFormat pageFormat, PMRect *paperRect)

PMGetCopies
[ Detail ]
Reports the number of copies that the user has requested to be printed.
OSStatus PMGetCopies(PMPrintSettings printSettings, UInt32 *copies)

PMGetDialogAccepted
[ Detail ]
Reports to application-defined callback functions whether the user has confirmed a dialog box.
OSStatus PMGetDialogAccepted(PMDialog pmDialog, Boolean *process)

PMGetDialogDone
[ Detail ]
Reports to application-defined callback functions whether a dialog box is needed any longer.
OSStatus PMGetDialogDone(PMDialog pmDialog, Boolean *done)

PMGetDialogPtr
[ Detail ]
Supplies the DialogRecord structure for the page setup or print dialog box.
OSStatus PMGetDialogPtr(PMDialog pmDialog, DialogPtr *theDialog)

PMGetDriverCreator
[ Detail ]
Identifies the creator of the current driver.
OSStatus PMGetDriverCreator(OSType *creator)

PMGetDriverReleaseInfo
[ Detail ]
Obtains release information about the current printer driver.
OSStatus PMGetDriverReleaseInfo(VersRec *release)

PMGetFirstPage
[ Detail ]
Reports the starting page number for a range of pages to be printed.
OSStatus PMGetFirstPage(PMPrintSettings printSettings, UInt32 *first)

PMGetGrafPtr
[ Detail ]
Obtains a printing port.
OSStatus PMGetGrafPtr(PMPrintContext printContext, GrafPtr *grafPort)

PMGetIndexedPrinterResolution
[ Detail ]
Obtains a particular resolution for the current printer.
OSStatus PMGetIndexedPrinterResolution(UInt32 index, PMResolution *res)

PMGetItemProc
[ Detail ]
Obtains your application-defined event handling function for a dialog box.
OSStatus PMGetItemProc(PMDialog pmDialog, PMItemUPP *itemProc)

PMGetJobName
[ Detail ]
Returns a Pascal string representing the job name for a printing session.
OSStatus PMGetJobName(PMPrintSettings printSettings, StringPtr name)

PMGetLanguageInfo
[ Detail ]
Reports the level, version, and release information about the imaging language of the current printer driver.
OSStatus PMGetLanguageInfo(PMLanguageInfo *info)

PMGetLastPage
[ Detail ]
Reports the last page number in the range of pages to be printed.
OSStatus PMGetLastPage(PMPrintSettings printSettings, UInt32 *last)

PMGetModalFilterProc
[ Detail ]
Obtains your application-defined event-handling function for a modal dialog box.
OSStatus PMGetModalFilterProc(PMDialog pmDialog, ModalFilterUPP *filterProc)

PMGetOrientation
[ Detail ]
Reports the current setting for page orientation.
OSStatus PMGetOrientation(PMPageFormat pageFormat, PMOrientation *orientation)

PMGetPageFormatExtendedData
[ Detail ]
Obtains additional page format data previously stored by your application.
OSStatus PMGetPageFormatExtendedData(PMPageFormat pageFormat, OSType dataID, UInt32 *size, void *theData)

PMGetPageRange
[ Detail ]
Reports the page numbers at which to begin and end printing.
OSStatus PMGetPageRange(PMPrintSettings printSettings, UInt32 *minPage, UInt32 *maxPage)

PMGetPhysicalPageSize
[ Detail ]
Returns the size of the imageable area in points, unaffected by rotation, resolution, or scaling.
OSStatus PMGetPhysicalPageSize(PMPageFormat pageFormat, PMRect *pageSize)

PMGetPhysicalPaperSize
[ Detail ]
Returns the true size of the paper in points, unaffected by rotation, resolution, or scaling.
OSStatus PMGetPhysicalPaperSize(PMPageFormat pageFormat, PMRect *paperSize)

PMGetPrintSettingsExtendedData
[ Detail ]
Obtains additional print settings previously saved by your application.
OSStatus PMGetPrintSettingsExtendedData(PMPrintSettings printSettings, OSType dataID, UInt32 *size, void *theData)

PMGetPrinterResolution
[ Detail ]
Obtains resolution information about the current printer.
OSStatus PMGetPrinterResolution(PMTag tag, PMResolution *res)

PMGetPrinterResolutionCount
[ Detail ]
Obtains the number of resolution settings for the current printer.
OSStatus PMGetPrinterResolutionCount(UInt32 *count)

PMGetResolution
[ Detail ]
Obtains the current drawing resolution of your application.
OSStatus PMGetResolution(PMPageFormat pageFormat, PMResolution *res)

PMGetScale
[ Detail ]
Returns the scaling factor currently applied to the page and paper rectangles.
OSStatus PMGetScale(PMPageFormat pageFormat, double *scale)

PMIdleProcPtr
[ Detail ]
Is called by the Carbon Printing Manager during your printing loop.
void PMIdleProcPtr()

PMIsPostScriptDriver
[ Detail ]
Reports whether the current printer driver supports the PostScript language.
OSStatus PMIsPostScriptDriver(Boolean *isPostScript)

PMItemProcPtr
[ Detail ]
Handles events involving application-added items in the dialog box.
void PMItemProcPtr(DialogPtr theDialog, SInt16 item)

PMMakeOldPrintRecord
[ Detail ]
Creates a Printing Manager print record from a PMPrintSettings object and a PMPageFormat object.
OSStatus PMMakeOldPrintRecord(PMPrintSettings printSettings, PMPageFormat pageFormat, Handle *prRecHdl)

PMNewPageFormat
[ Detail ]
Creates a new object for containing page format information.
OSStatus PMNewPageFormat(PMPageFormat *pageFormat)

PMNewPrintSettings
[ Detail ]
Creates a new object for containing print settings.
OSStatus PMNewPrintSettings(PMPrintSettings *printSettings)

PMPageSetUpDialog
[ Detail ]
Displays the page setup dialog box for the current printer.
OSStatus PMPageSetUpDialog(PMPageFormat pageFormat, Boolean *accepted)

PMPageSetUpDialogInit
[ Detail ]
Initializes a customized page setup dialog box.
OSStatus PMPageSetUpDialogInit(PMPageFormat pageFormat, PMDialog *newDIalog)

PMPageSetUpDialogInitProcPtr
[ Detail ]
Creates a custom page setup dialog box when called by the Carbon Printing Manager.
void PMPageSetUpDialogInitProcPtr(PMPageFormat pageFormat, PMDialog *theDialog)

PMPageSetUpDialogMain
[ Detail ]
Displays a customized page setup dialog box.
OSStatus PMPageSetUpDialogMain(PMPageFormat pageFormat, Boolean *accepted, PMPageSetUpDialogInitUPP myInitProc)

PMPostScriptBegin
[ Detail ]
Enables PostScript imaging.
OSStatus PMPostScriptBegin()

PMPostScriptData
[ Detail ]
Passes PostScript data during your drawing loop.
OSStatus PMPostScriptData(Ptr data, Size len)

PMPostScriptEnd
[ Detail ]
Disables PostScript imaging.
OSStatus PMPostScriptEnd()

PMPostScriptFile
[ Detail ]
Passes a PostScript data file during your drawing loop.
OSStatus PMPostScriptFile(FSSpec *theFile)

PMPostScriptHandle
[ Detail ]
Passes PostScript data during your drawing loop.
OSStatus PMPostScriptHandle(Handle postScript)

PMPrintDialog
[ Detail ]
Displays a dialog box requesting the user to specify settings for a print job.
OSStatus PMPrintDialog(PMPrintSettings printSettings, PMPageFormat constPageFormat, Boolean *accepted)

PMPrintDialogInit
[ Detail ]
Initializes a custom print dialog box.
OSStatus PMPrintDialogInit(PMPrintSettings printSettings, PMDialog *newDialog)

PMPrintDialogInitProcPtr
[ Detail ]
Creates a custom print dialog box when called by the Carbon Printing Manager.
void PMPrintDialogInitProcPtr(PMPrintSettings printSettings, PMDialog *theDialog)

PMPrintDialogMain
[ Detail ]
Displays a custom print dialog box.
OSStatus PMPrintDialogMain(PMPrintSettings printSettings, PMPageFormat constPageFormat, Boolean *accepted, PMPrintDialogInitUPP myInitProc)

PMSetCopies
[ Detail ]
Sets the default value to be displayed in the print dialog box for the number of copies to be printed.
OSStatus PMSetCopies(PMPrintSettings printSettings, UInt32 copies, Boolean lock)

PMSetDialogAccepted
[ Detail ]
Informs the Carbon Printing Manager that your application-defined callback function has accepted a dialog box and is processing a print request.
OSStatus PMSetDialogAccepted(PMDialog pmDialog, Boolean process)

PMSetDialogDone
[ Detail ]
Informs the Carbon Printing Manager that your application-defined callback function no longer needs a dialog box.
OSStatus PMSetDialogDone(PMDialog pmDialog, Boolean done)

PMSetError
[ Detail ]
Sets the value of the current printing error.
OSStatus PMSetError(OSStatus printError)

PMSetFirstPage
[ Detail ]
Sets for the print dialog box the page number at which to begin printing.
OSStatus PMSetFirstPage(PMPrintSettings printSettings, UInt32 first, Boolean lock)

PMSetIdleProc
[ Detail ]
Sets your application-defined idle function for the printing loop.
OSStatus PMSetIdleProc(PMIdleUPP idleProc)

PMSetItemProc
[ Detail ]
Sets your application-defined event-handling function for items in a custom dialog box.
OSStatus PMSetItemProc(PMDialog pmDialog, PMItemUPP itemProc)

PMSetJobName
[ Detail ]
Associates a name with a print session.
OSStatus PMSetJobName(PMPrintSettings printSettings, StringPtr name)

PMSetLastPage
[ Detail ]
Sets for the print dialog box the page number at which to end printing.
OSStatus PMSetLastPage(PMPrintSettings printSettings, UInt32 last, Boolean lock)

PMSetModalFilterProc
[ Detail ]
Sets your event-handling function for a Carbon Printing Manager modal dialog box.
OSStatus PMSetModalFilterProc(PMDialog pmDialog, ModalFilterUPP filterProc)

PMSetOrientation
[ Detail ]
Sets the page orientation for printing.
OSStatus PMSetOrientation(PMPageFormat pageFormat, PMOrientation orientation, Boolean lock)

PMSetPageFormatExtendedData
[ Detail ]
Stores your application-supplied data with a PMPageFormat object.
OSStatus PMSetPageFormatExtendedData(PMPageFormat pageFormat, OSType dataID, UInt32 size, void *theData)

PMSetPageRange
[ Detail ]
Sets for the print dialog box the page numbers at which to begin and end printing.
OSStatus PMSetPageRange(PMPrintSettings printSettings, UInt32 minPage, UInt32 maxPage)

PMSetPhysicalPaperSize
[ Detail ]
Sets printing to a particular paper size, unaffected by rotation, resolution, or scaling.
OSStatus PMSetPhysicalPaperSize(PMPageFormat pageFormat, const PMRect paperSize)

PMSetPrintSettingsExtendedData
[ Detail ]
Stores application-supplied data with a PMPrintSettings object.
OSStatus PMSetPrintSettingsExtendedData(PMPrintSettings printSettings, OSType dataID, UInt32 size, void *theData)

PMSetProfile
[ Detail ]
Embeds a color profile during printing.
OSStatus PMSetProfile(PMPrintSettings printSettings, PMTag tag, const CMProfileLocation profile)

PMSetResolution
[ Detail ]
Sets your application drawing resolution.
OSStatus PMSetResolution(PMPageFormat pageFormat, const PMResolution res)

PMSetScale
[ Detail ]
Sets print scaling.
OSStatus PMSetScale(PMPageFormat pageFormat, double scale)

PMUnFlattenPageFormat
[ Detail ]
Rebuilds a flattened PMPageFormat object.
OSStatus PMUnFlattenPageFormat(Handle flatFormat, PMPageFormat *pageFormat)

PMUnFlattenPrintSettings
[ Detail ]
Rebuilds a flattened PMPrintSettings object.
OSStatus PMUnFlattenPrintSettings(Handle flatSetting, PMPrintSettings *printSettings)

PMValidatePageFormat
[ Detail ]
Ensures that the page setup information is compatible with the driver for the current printer.
OSStatus PMValidatePageFormat(PMPageFormat pageFormat, Boolean *formatResult)

PMValidatePrintSettings
[ Detail ]
Ensures that the print settings are compatible with the driver for the current printer.
OSStatus PMValidatePrintSettings(PMPrintSettings printSettings, Boolean *settingResult)


Last modified: 5/7/99. Status: Draft Copyright 1999 Apple Computer, Inc. All rights reserved.